home *** CD-ROM | disk | FTP | other *** search
/ LSD Docs / LSD Docs.iso / FILEZ / lsd08.dms / lsd08.adf / 73 / 73
Text File  |  1990-02-22  |  13KB  |  413 lines
  1.                         POWERPACKER LIBRARY
  2.  
  3. Typed in by ???. Edited by PARASITE.
  4.  
  5.  
  6. TABLE OF CONTENTS
  7. powerpacker.library/ppLoadData
  8. powerpacker.library/ppDecrunchBuffer
  9. powerpacker.library/ppCalcChecksum
  10. powerpacker.library/ppCalcPasskey
  11. powerpacker.library/ppDecrypt
  12. powerpacker.library/ppGetPassword
  13. powerpacker.library/ppGetString
  14. powerpacker.library/ppGetLong
  15.  
  16.  
  17. powerpacker.library/ppLoadData
  18.  
  19.   NAME  ppLoadData()
  20.  
  21.     error = ppLoadData (filename, col, memtype, &buffer, &len, func);
  22.  
  23.     ULONG ppLoadData (char *, ULONG, ULONG, UBYTE **, ULONG *, BOOL (*)());
  24.     D0                A0      D0     D1     A1        A2       A3
  25.  
  26.   DESCRIPTION
  27.     This function loads a file in memory. The memory necessary to load the
  28.     file will be allocated by this function. Files crunched with PowerPacker
  29.     will be decrunched, plain files will simply be loaded. If the file can't
  30.     be opened ".pp" will be appended before trying again. The address of the
  31.     loaded file will be stored in 'buffer', the length in 'len'. You must
  32.     free this memory yourself (see NOTE) !
  33.  
  34.     The 'func' argument is the address of a function to be called when
  35.     ppLoadData() needs a password to decrypt an encrypted file. If you do
  36.     not want to load encrypted files call with func equal to -1, if you want
  37.     ppLoadData() to use ppGetPassword(), call with func equal to NULL.
  38.  
  39.     If you wish to use your own password prompting function you must call
  40.     ppLoadData() with func equal to the address of this type of function:
  41.  
  42.         BOOL __stdargs myFunction (UBYTE *password, UWORD checksum);
  43.  
  44.     On entry 'password' points to a buffer to hold up to 16 characters and a
  45.     terminating zero (so 17 bytes in all), 'checksum' is the checksum of the
  46.     password we are looking for. Your function must prompt for a string and
  47.     compare the checksum with 'checksum' (use ppCalcChecksum() for this). If
  48.     they are equal you must store the string in 'password' (in C you can use
  49.     'strcpy') and return TRUE, if not you should give the user a few more
  50.     chances (usually three in all) and return FALSE if no correct password
  51.     was entered. The two arguments are pushed on the stack according to C
  52.     convention, so if you write your function in assembly you will find the
  53.     arguments on the stack, the pointer to the buffer at 4(a7) and the
  54.     checksum at 8(a7) (longword !). Assembly functions must preserve all
  55.     registers !
  56.  
  57.   INPUTS
  58.     filename - pointer to a null terminated pathname of the file to load.
  59.     col      - the effect to be used during decrunching. One of the
  60.                following (defined in "libraries/ppbase.[hi]"):
  61.                    DECR_COL0    - flash color 0
  62.                    DECR_COL1    - flash color 1
  63.                    DECR_POINTER - flash mouse pointer
  64.                    DECR_SCROLL  - weird stuff :-)
  65.                    DECR_NONE    - no decrunching effect
  66.     memtype  - type of memory to allocate (see AllocMem()).
  67.     &buffer  - address of (!) variable to hold memory location of loaded
  68.                file.
  69.     &len     - address of (!) variable to hold length of loaded file.
  70.     func     - function to be called to prompt the user for a password,
  71.                NULL for the the default password prompt and -1 for no
  72.                password prompt.
  73.  
  74.   RESULT
  75.     error - 0 if all went ok, if not one of the following error codes will
  76.             be returned (defined in "libraries/ppbase.(h|i)"):
  77.                 PP_OPENERR   - unable to open file.
  78.                 PP_READERR   - read error.
  79.                 PP_NOMEMORY  - not enough memory to load file.
  80.                 PP_CRYPTED   - file is encrypted (only when 'func' == -1).
  81.                 PP_PASSERR   - incorrect password, 'func()' returned FALSE.
  82.                 PP_UNKNOWNPP - crunched by unknown version of PowerPacker.
  83.  
  84.   NOTE
  85.     Do not forget to free the memory allocated by this function !
  86.     Use "FreeMem (buffer, len);" before quitting your program, but only if
  87.     ppLoadData() didn't return an error.
  88.  
  89.     After calling 'func()' ppLoadData() doesn't check the checksum again,
  90.     only the returned boolean. Therefore it is VERY important that your
  91.     function is correct and only returns TRUE when the entered password has
  92.     the correct checksum !
  93.     Don't forget to copy your string to the memory pointed to by 'password'
  94.     before leaving 'func()' ! This password is needed to decrypt the file !!
  95.     Note that 'password' is a C string and must be null terminated !
  96.  
  97.     In case you call ppLoadData() with 'func' equal to NULL (use automatic
  98.     password prompting) the pr_WindowPtr of your Process will be used to
  99.     find the screen to open the password requester on. If pr_WindowPtr
  100.     equals 0 or -1 the WorkBench screen will be used, otherwise the screen
  101.     of the pr_WindowPtr window will be used. Only a process can call
  102.     ppLoadData() (it uses DOS) so pr_WindowPtr exists. Set it like this:
  103.  
  104.         struct Window *yourwindow;
  105.         struct Process *proc;
  106.         APTR oldwinptr;
  107.  
  108.         /* Open your screen and window... */
  109.  
  110.         ...
  111.  
  112.         /* set pr_WindowPtr */
  113.         proc = (struct Process *)FindTask (NULL);
  114.         oldwinptr = proc->pr_WindowPtr;
  115.         proc->pr_WindowPtr = (APTR)yourwindow;
  116.  
  117.         ...
  118.  
  119.         /* restore before quitting (VERY IMPORTANT !!) */
  120.         proc->pr_WindowPtr = oldwinptr;
  121.         exit (0);
  122.  
  123.   BUGS
  124.     none known
  125.  
  126.   SEE ALSO
  127.     exec.library/AllocMem()
  128.     exec.library/FreeMem()
  129.     ppCalcChecksum()
  130.     ppGetPassword()
  131.  
  132.  
  133. powerpacker.library/ppDecrunchBuffer
  134.  
  135.   NAME  ppDecrunchBuffer()
  136.  
  137.     ppDecrunchBuffer (endcrun, decrbuff, effptr, col);
  138.  
  139.     void ppDecrunchBuffer (UBYTE *, UBYTE *, ULONG *, ULONG);
  140.                            A0       A1       A2       D0
  141.  
  142.   DESCRIPTION
  143.     Function to decrunch from one memory location to another. The address of
  144.     the destination can be as close as 8 bytes after the start address of
  145.     the source, so you can decrunch a file with almost no memory overhead.
  146.  
  147.     If you wish to call this function you need to know the format of a
  148.     crunched file:
  149.  
  150.         1 longword identifier           'PP20' or 'PX20'
  151.        [1 word checksum (if 'PX20')     $ssss]
  152.         1 longword efficiency           $eeeeeeee
  153.         X longwords crunched file       $cccccccc,$cccccccc,...
  154.         1 longword decrunch info        'decrlen' << 8 | '8 bits other info'
  155.  
  156.     The following procedure must be followed to decrunch a file:
  157.  
  158.     First you must read 'decrunch info' to find the length of the decrunched
  159.     file, then you must allocate memory to decrunch it in (shift 'decrunch
  160.     info' right 8 bits and add a safety margin (8 bytes) to get the length
  161.     of this memory block).  If the file is encrypted ('PX20') you must call
  162.     ppDecrypt to decrypt the crunched part before calling ppDecrunchBuffer.
  163.  
  164.     So:
  165.     - read identifier.
  166.     - if PX20, read checksum.
  167.     - read efficiency.
  168.     - allocate 'decrlen' + 8 (safety margin) bytes.
  169.     - load 'crunched file' and 'decrunch info' at start of allocated memory.
  170.     - if PX20, prompt for a password (compare checksum !).
  171.     - if PX20, calculate the passkey (use ppCalcPasskey).
  172.     - if PX20, call ppDecrypt to decrypt 'crunched file' only.
  173.       (NOT 'decrunch info' !)
  174.     - and finally call ppDecrunchBuffer() with 'endcrun' pointing right after
  175.       'decrunch info', 'decrbuff' pointing 8 bytes after where you loaded the
  176.       file and 'effptr' pointing to the 'efficieny' longword.
  177.  
  178.     If this seems complicated that is probably because it is :-) ppLoadData
  179.     was written to make things simpler and should suffice for most cases.
  180.  
  181.   INPUTS
  182.     endcrun  - pointer just after the last byte of the crunched block.
  183.     decrbuff - pointer to beginning of memory to decrunch to (this must be
  184.                at least 8 bytes behind the start of the crunched file).
  185.     effptr   - pointer to efficiency table.
  186.     col      - decrunching effect (see ppLoadData).
  187.  
  188.   RESULT
  189.     none
  190.  
  191.   NOTE
  192.     This function is used by ppLoadData() and will probably not be used very
  193.     often on its own.
  194.  
  195.   BUGS
  196.     none known
  197.  
  198.   SEE ALSO
  199.     ppLoadData()
  200.     ppDecrypt()
  201.     ppCalcPasskey()
  202.     ppCalcChecksum()
  203.     ppGetPassword()
  204.  
  205.  
  206. powerpacker.library/ppCalcChecksum
  207.  
  208.   NAME  ppCalcChecksum()
  209.  
  210.     sum = ppCalcChecksum (string);
  211.  
  212.     UWORD ppCalcChecksum (char *);
  213.     D0                    A0
  214.  
  215.   DESCRIPTION
  216.     This function calculates a 16 bit checksum of a given string of
  217.     characters.
  218.  
  219.   INPUTS
  220.     string - pointer to a null terminated character string.
  221.  
  222.   RESULT
  223.     sum - checksum of 'string'.
  224.  
  225.   NOTE
  226.     Function used to check if a password is correct.
  227.  
  228.   BUGS
  229.     none
  230.  
  231.   SEE ALSO
  232.     ppLoadData()
  233.     ppDecrunchBuffer()
  234.     ppDecrypt()
  235.     ppCalcPasskey()
  236.  
  237.  
  238. powerpacker.library/ppCalcPasskey
  239.  
  240.   NAME  ppCalcPasskey()
  241.  
  242.     key = ppCalcPasskey (password);
  243.  
  244.     ULONG ppCalcPasskey (char *);
  245.     D0                   A0
  246.  
  247.   DESCRIPTION
  248.  
  249.   INPUTS
  250.     string - pointer to a null terminated character string.
  251.  
  252.   RESULT
  253.     key - passkey corresponding to the given password.
  254.  
  255.   NOTE
  256.     Function used to decrypt encrypted files.
  257.  
  258.   BUGS
  259.     none
  260.  
  261.   SEE ALSO
  262.     ppDecrunchBuffer()
  263.     ppDecrypt()
  264.     ppCalcChecksum()
  265.  
  266.  
  267. powerpacker.library/ppDecrypt
  268.  
  269.   NAME  ppDecrypt()
  270.  
  271.     ppDecrypt (buffer, len, key)
  272.  
  273.     void ppDecrypt (UBYTE *, ULONG, ULONG);
  274.                     A0       D0     D1
  275.  
  276.   DESCRIPTION
  277.     This function will decrypt a memory region with a given passkey. It
  278.     must be called before calling ppDecrunchBuffer() (if the file was
  279.     encrypted).
  280.  
  281.   INPUTS
  282.     buffer - start address of memory region to decrypt (word alligned !).
  283.     len    - length in bytes of memory region to decrypt (rounded up to the
  284.              next multiple of 4).
  285.     key    - key of password as returned by ppCalcPasskey().
  286.  
  287.   RESULT
  288.     none
  289.  
  290.   NOTE
  291.     If you call this function before calling ppDecrunchBuffer make sure you
  292.     decrypt the correct memory region, don't decrypt the last longword !
  293.  
  294.   BUGS
  295.     none
  296.  
  297.   SEE ALSO
  298.     ppDecrunchBuffer()
  299.     ppCalcChecksum()
  300.     ppCalcPasskey()
  301.     ppLoadData()
  302.  
  303.  
  304. powerpacker.library/ppGetPassword
  305.  
  306.   NAME  ppGetPassword()
  307.  
  308.     bool = ppGetPassword (screen, buffer, maxchars, checksum);
  309.  
  310.     BOOL ppGetPassword (struct Screen *, UBYTE *, ULONG, UWORD);
  311.     D0                  A0               A1       D0     D1
  312.  
  313.   DESCRIPTION
  314.     Opens a small requester to prompt the user for a password. Returns when
  315.     the user enters a password with a checksum equal to 'checksum' or when
  316.     he has failed to enter a correct password (three chances). The password
  317.     will not be visible when typed.
  318.  
  319.   INPUTS
  320.     screen   - address of Intuition screen where requester should appear,
  321.                or NULL for WorkBench screen.
  322.     buffer   - buffer to hold correct password.
  323.     maxchars - maximum number of characters in password (should be 16,
  324.                buffer should be at least 17 bytes big !).
  325.     checksum - checksum of password we are looking for.
  326.  
  327.   RESULT
  328.     bool - TRUE when the correct password was entered (can be found in
  329.            buffer), FALSE when no correct password was given after three
  330.            tries.
  331.  
  332.   NOTE
  333.     This function will be used by ppLoadData() to prompt for a password when
  334.     you called it with 'func' equal to NULL.
  335.  
  336.     Automatically adjusts the requester to the screens font.
  337.  
  338.   BUGS
  339.     none known
  340.  
  341.   SEE ALSO
  342.     ppLoadData()
  343.     ppDecrunchBuffer()
  344.  
  345.  
  346. powerpacker.library/ppGetString
  347.  
  348.   NAME  ppGetString()
  349.  
  350.     bool = ppGetString (screen, buffer, maxchars, title);
  351.  
  352.     BOOL ppGetString (struct Screen *, UBYTE *, ULONG, char *);
  353.     D0                A0               A1       D0     A2
  354.  
  355.   DESCRIPTION
  356.     Puts up a string requester to get a line of text from the user.
  357.     The string present in 'buffer' upon entry will be displayed, ready to
  358.     be edited.
  359.  
  360.   INPUTS
  361.     screen   - address of Intuition screen where requester should appear,
  362.                or NULL for WorkBench screen.
  363.     buffer   - pointer to buffer to hold characters entered.
  364.     maxchars - maximum number of characters that fit in buffer (EX-cluding
  365.                the 0 to terminate the string !).
  366.     title    - pointer to null terminated title of requester window.
  367.  
  368.   RESULT
  369.     bool - TRUE if user entered something, FALSE otherwise (empty buffer).
  370.  
  371.   NOTE
  372.     Doesn't have much to do with PowerPacker, but was put in because it is
  373.     a useful function and it only required a small amount of code (using
  374.     the main part of the ppGetPassword() function).
  375.  
  376.     Automatically adjusts the requester to the screens font.
  377.  
  378.   BUGS
  379.     none known
  380.  
  381.   SEE ALSO
  382.  
  383.  
  384. powerpacker.library/ppGetLong
  385.  
  386.   NAME  ppGetLong()
  387.  
  388.     bool = ppGetLong (screen, &longvar, title);
  389.  
  390.     BOOL ppGetLong (struct Screen *, ULONG *, char *);
  391.     D0              A0               A1       A2
  392.  
  393.   DESCRIPTION
  394.     Puts up a requester to get a signed long (32-bit) number from the user.
  395.  
  396.   INPUTS
  397.     screen   - address of Intuition screen where requester should appear,
  398.                or NULL for WorkBench screen.
  399.     &longvar - address of (!) long (32 bit) variable to hold result.
  400.     title    - points to null terminated title of requester window.
  401.  
  402.   RESULT
  403.     bool - TRUE if user entered a number, FALSE if not.
  404.  
  405.   NOTE
  406.     Doesn't have much to do with PowerPacker, but was put in because it is
  407.     a useful function and it only required a small amount of code (using
  408.     the main part of the ppGetPassword() function).
  409.  
  410.     Automatically adjusts the requester to the screens font.
  411.  
  412. End.
  413.